Inside Macintosh: QuickTime Components

Previous | Chapter Top | Chapter Contents | Next

Setting Default Parameters

The standard dialog component stores and manages a set of compression parameters for your application. Before presenting the dialog box to the user, you may want to set default values for these parameters. The standard dialog component provides a number of options for establishing these default values:

1. You may supply an image to the component from which it can derive default settings. The component examines the characteristics of the image and sets appropriate default values. The SCDefaultPictHandleSettings function works with images stored in picture handles; the SCDefaultPictFileSettings function works with images stored in picture files; and the SCDefaultPixMapSettings function works with pixel maps. These functions are discussed in "Getting Default Settings for an Image or a Sequence," .
2. If you have not set any defaults, but you do supply a test image for the dialog, the component examines the test image and derives appropriate default values based upon its characteristics. The next section discusses how to assign a test image to the user dialog box.
3. If you have not set any defaults and do not supply a test image, the component uses its own default values.
4. You may modify the settings by using the SCSetInfo function, which is described on SCSetInfo . This function gives you a great deal of freedom--you can use it to modify any of the parameters stored by the component.

If you supply either a test or a default image, the standard dialog component extracts default compression settings from that image, including color table, grayscale information (if appropriate), and compression defaults (if the source image is already compressed). If any of these default values differ from your needs, use the SCSetInfo function to modify the value.

Designating a Test Image

The standard image-compression dialog component provided by Apple supports a test image in its dialog box. The component uses this test image to show the user the effect of the current set of compression parameters. Whenever the user changes the dialog box settings, the component applies those parameters to the test image and displays the results in its dialog box. In addition, the standard dialog component may sometimes use the test image to obtain hints about the type of compression operation you expect to perform. In some cases, the component may derive default parameter values by examining the test image.

The component provides three functions that allow you to specify a dialog box's test image. Each of these functions uses a different image source--a handle, a picture file, or a pixel map. Your application is responsible for obtaining the image and for disposing of it after you are done.

The test image portion of the dialog box supported by Apple's standard image-compression dialog component is a square measuring 80 pixels by 80 pixels. In order to deal with test images that are larger than this area, Apple's component allows you to specify a part of the image to display. You can specify an area of interest, which indicates a portion of the test image that is to be displayed in the dialog box. If the area of interest is still larger than the display area in the dialog box, the component may shrink the image or crop it (or both) until the image fits.

Listing 1 shows one way to specify a test image. This code fragment uses an image that is stored in a picture file. The program asks the user to specify the file, using the SFGetFilePreview function. The program then opens the image file and instructs the standard image-compression dialog component to use the picture that is stored in the file.

Listing 1 Specifying a test image

Point                   where;
ComponentInstance       ci;
SFTypeList              typeList;
SFReply                 inReply;
short                   srcPictFRef;

where.h = where.v = -2;                     /* center dialog box on the
                                                 best screen */
typeList[0] = 'PICT';                       /* set file type */

SFGetFilePreview (where, "\p", nil, 1, typeList, nil,
                    &inReply);
if (!inReply.good) {     /* handle error */
}

result = FSOpen (inReply.fName, inReply.vRefNum, &srcPictFRef);
if (result) {               /* handle error */
}

result = SCSetTestImagePictFile
            (ci,                            /* component connection */
            srcPictFRef,                    /* source picture file */
            nil,                            /* use the entire image */
            scPreferScalingAndCropping);
                                            /* shrink image and crop it */
if (result) {                               /* handle error */
}   


Displaying the Dialog Box and Retrieving Parameters

Standard image-compression dialog components provide two functions that display the dialog box to the user and retrieve the user's compression settings: SCRequestImageSettings and SCRequestSequenceSettings . Both of these functions start with your default parameter settings. Any changes made by the user are stored by the component. You may use the SCGetInfo function to examine these settings.

The SCRequestImageSettings function obtains image-compression parameters from the user and displays the dialog box that is shown in Figure 1 . The SCRequestSequenceSettings function works with sequence-compression parameters, using the dialog box shown in Figure 2 . Both of these functions allow you to augment or extend the interface in the dialog box--see "Extending the Basic Dialog Box," which begins on Extending the Basic Dialog Box , for more information about extending the basic dialog boxes.

Listing 2 shows how to use the SCRequestImageSettings function to display the dialog box to the user and obtain the resulting image-compression settings. This code fragment obtains the compression parameters from the user and then uses those parameters to compress the image that is stored in the file the user selected in Listing 1 . The program then stores the compressed image in a different file--this fragment assumes that the destination file has already been selected.

Listing 2 Displaying the dialog box to the user and compressing an image

ComponentInstance           ci;                 /* component connection */
short                       srcPictFRef;        /* source file */
short                       dstPictFRef;        /* destination file */

result = SCRequestImageSettings(ci);
if (result < 0) {                               /* handle error */
}
if (result == scUserCancelled) {                /* user clicked Cancel
                                                    button */
}
result = SCCompressPictureFile
            (ci,                                /* component connection */
            srcPictFRef,                        /* source picture file */
            dstPictFRef);                       /* dest picture file */
if (result < 0) {                               /* handle error */
}


Note that, because the standard dialog component stores the compression parameters for you, the new user settings become the default values the next time your application interacts with the user. If this is inappropriate, use one of the mechanisms discussed in "Setting Default Parameters" to modify those defaults.